<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>stat</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_008_837">&nbsp;</a>NAME</h4><blockquote>
stat - get file status
</blockquote><h4><a name = "tag_000_008_838">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="systypes.h.html">sys/types.h</a>&gt;
#include &lt;<a href="sysstat.h.html">sys/stat.h</a>&gt;

int stat(const char *<i>path</i>, struct stat *<i>buf</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_008_839">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>stat()</i>
function obtains information about the named file and writes it
to the area pointed to by the
<i>buf</i>
argument.
The
<i>path</i>
argument points to a pathname naming a file.  Read, write or execute
permission of the named file is not required, but all directories listed in
the pathname leading to the file must be searchable.  An implementation that
provides additional or alternate file access control mechanisms may, under
implementation-dependent conditions, cause
<i>stat()</i>
to fail.  In particular, the system may deny the existence of the
file specified by
<i>path</i>.
<p>
The
<i>buf</i>
argument is a pointer to a
<i>stat</i>
structure, as defined in the header
<i><a href="sysstat.h.html">&lt;sys/stat.h&gt;</a></i>,
into which information is placed concerning the file.
<p>
The
<i>stat()</i>
function updates any time-related fields (as described in the definition of
<b>File Times Update</b>
in the <b>XBD</b> specification), before writing into the
<b>stat</b>
structure.
<p>
The structure members
<i>st_mode</i>,
<i>st_ino</i>,
<i>st_dev</i>,
<i>st_uid</i>,
<i>st_gid</i>,
<i>st_atime</i>,
<i>st_ctime</i>
and
<i>st_mtime</i>
will have meaningful values for all file types defined in this document.
The value of the member
<i>st_nlink</i>
will be set to the number of links to the file.
</blockquote><h4><a name = "tag_000_008_840">&nbsp;</a>RETURN VALUE</h4><blockquote>
Upon successful completion, 0 is returned.  Otherwise, -1 is returned and
<i>errno</i>
is set to indicate the error.
</blockquote><h4><a name = "tag_000_008_841">&nbsp;</a>ERRORS</h4><blockquote>
The
<i>stat()</i>
function will fail if:
<dl compact>

<dt>[EACCES]<dd>
Search permission is denied for a component of the path prefix.

<dt>[EIO]<dd>
An error occurred while reading from the file system.

<dt>[ELOOP]<dd>
Too many symbolic links were encountered in resolving <i>path</i>.

<dt>[ENAMETOOLONG]<dd>

The length of the
<i>path</i>
argument exceeds {PATH_MAX} or a pathname component is longer than
{NAME_MAX}.

<dt>[ENOENT]<dd>
A component of <i>path</i> does not name an existing file
or <i>path</i> is an empty string.

<dt>[ENOTDIR]<dd>
A component of the path prefix is not a directory.

<dt>[EOVERFLOW]<dd>
The file size in bytes or the number of blocks allocated to the file
or the file serial number cannot be represented correctly in the
structure pointed to by 
<i>buf</i>.

</dl>
<p>
The
<i>stat()</i>
function may fail if:
<dl compact>

<dt>[ENAMETOOLONG]<dd>

Pathname resolution of a symbolic link produced an intermediate result whose
length exceeds {PATH_MAX}.

<dt>[EOVERFLOW]<dd>
A value to be stored would overflow one of the members
of the <b>stat</b> structure.

</dl>
</blockquote><h4><a name = "tag_000_008_842">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_008_843">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_008_844">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_008_845">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="fstat.html">fstat()</a></i>,
<i><a href="lstat.html">lstat()</a></i>,
<i><a href="sysstat.h.html">&lt;sys/stat.h&gt;</a></i>,
<i><a href="systypes.h.html">&lt;sys/types.h&gt;</a></i>.
</blockquote><h4>DERIVATION</h4><blockquote>
Derived from Issue 1 of the SVID.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>

